Problem

The Install LaTeX from cache step in .github/workflows/sphinxbuild.yml is too slow — it hits a 5-minute timeout because dpkg -i unpacking all texlive .deb files from the apt cache takes too long. The current approach caches .deb files but still re-runs dpkg on every job.

Solution

Replace the current .deb-based cache approach with a cached installed files approach:

1. After installing LaTeX via apt-get, copy the installed files to ~/.cache/latex-installed/ (a home-relative path safe for actions/cache)
2. On cache hit, restore those files by copying them back to their system destinations using sudo cp
3. This makes the actions/cache action work without permission issues (it only touches the home path), while a simple sudo cp handles the privileged restore

Implementation

Modify .github/workflows/sphinxbuild.yml:

In the setup-latex-cache job

Replace the current apt download-only + .deb cache approach with:

• Install LaTeX fully via apt-get install (not --download-only)
• Copy installed files to ~/.cache/latex-installed/ covering all relevant paths:
  • /usr/share/texlive → ~/.cache/latex-installed/texlive
  • /usr/share/texmf → ~/.cache/latex-installed/texmf
  • All relevant binaries from /usr/bin/ (latexmk, xelatex, pdflatex, lualatex, xindy, etc.) — use dpkg -L on each package to find the exact binaries
  • Any config files in /etc/texmf/ → ~/.cache/latex-installed/etc-texmf
  • Perl/lib files that texlive depends on (check dpkg -L output)
• chown -R $(id -u):$(id -g) the cache dir so actions/cache can save it
• Cache the ~/.cache/latex-installed/ path with actions/cache/save

In the build job

Replace the current "Restore LaTeX apt cache" + "Install LaTeX from cache" steps with:

• Restore ~/.cache/latex-installed/ via actions/cache/restore
• A single restore step that uses sudo cp -r to put everything back in system paths
• Handle binaries, shared data, config, and any symlinks correctly
• Make sure the restored install is fully functional for latexmk, xelatex, pdflatex, and xindy

Key requirements

• Use dpkg -L for all installed packages to get the complete, accurate file list — do not guess paths
• The cache key should reflect the package set and OS version (similar to current key format)
• The setup-latex-cache job should still use lookup-only on first check to skip re-running if cache already exists
• Restore must be fast — the whole point is to avoid the slow dpkg unpack on every build
• Remove the now-unnecessary timeout-minutes: 5 that was causing failures
• Remove the old .deb cache paths and related steps entirely

The cache size may be large (~1-2GB) — that's acceptable given the speed improvement.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Is it possible to have the workflow update the runner image by installing dependencies, and then use that image in the following jobs ? Because it seems even installing the packages takes too much time/cpu

Assistant: ## Short answer: Not natively — but there's a better approach

GitHub Actions jobs always start from a fresh runner image — you can't mutate a runner in one job and pass that modified state to the next. Each job is an isolated VM.

The right solution for your use case is a custom Docker image stored in GHCR with LaTeX pre-installed. This avoids the install overhead entirely since the packages are baked into the image layer.

The real problem

Looking at the failing job, the Install LaTeX from cache step is hitting a 5-minute timeout while running sudo dpkg -i --force-depends on all the texlive .deb files. That's a lot of large packages to unpack sequentially.

Recommended fix: Pre-built Docker image on GHCR

Create a Dockerfile and a separate workflow that builds + publishes it to GHCR. Then use it as the container in your build jobs.

1. Add a Dockerfile:

FROM ubuntu:24.04

RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    python3-pil python3-pip \
    texlive-fonts-recommended latexmk \
    texlive-latex-extra texlive-latex-recommended texlive-xetex \
    texlive-fonts-extra-links texlive-fonts-extra xindy tex-gyre \
    make git \
  && rm -rf /var/lib/apt/lists/*

2. Add a workflow to build & publish the image:

name: Build Sphinx+LaTeX image

on:
  push:
    paths:
      - '.docker/sphinx-latex/**'
    branches: [master]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: d...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>